home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / bnslib.arc / BNSLIB.DOC next >
Encoding:
Text File  |  1987-08-26  |  37.3 KB  |  812 lines
  1.                     BNSLIB - An Object Module Library Manager
  2.                                   User's Guide
  3.                     Copyright (C) 1987 by Brand Name Software
  4.                                All Rights Reserved
  5.  
  6.  
  7.  
  8.      Commercial Announcement:
  9.  
  10.          This  product  is  offered  as user-supported software.  If you
  11.          find it useful, please send your (printed)  name  and  address,
  12.          the version number of your copy, and $10 to:
  13.  
  14.                     Brand Name Software
  15.                     1365 N. Broadway
  16.                     Suite 111
  17.                     Walnut Creek, CA 94596
  18.  
  19.          This  will  make  you  a  'registered  user'  of  BNSLIB.  As a
  20.          registered user, you will be notified by mail  (electronic,  if
  21.          possible)  of any major updates to the program.  Also, you will
  22.          have the satisfaction of knowing you are supporting development
  23.          of future, improved, versions of this product.
  24.  
  25.          Support  for this product is available to REGISTERED USERS ONLY
  26.          via CompuServe by leaving a message on the Programmers' SIG (GO
  27.          PROGSIG)  for  *sysop (the asterisk is important) or by leaving
  28.          an EasyPlex (electronic mail) message for User  ID  76703,1005.
  29.          If  you  have  a  MCI Mail account, you can also get support by
  30.          leaving an electronic message for BPAULSEN (CompuServe  support
  31.          will  be faster -- the MCI mailbox is only checked about once a
  32.          week, CompuServe is checked at least once per day, seven days a
  33.          week).
  34.  
  35.  
  36.      A Simple License:
  37.  
  38.          BNSLIB  is  licensed, at no charge, subject  to  the  following
  39.          terms and conditions:
  40.  
  41.          1.  You may copy this program and its related  documentation as
  42.              many times as you wish, provided that the copyright  notice
  43.              and  disclaimers  of  warranty  are reproduced in full each
  44.              time.
  45.  
  46.          2.  Copies of this  program  may  not  be  sold  without  prior
  47.              written consent of Brand Name Software.
  48.  
  49.          3.  The program and  its  related  documentation  are  supplied
  50.              as-is. Brand Name Software hereby disclaims all warranties,
  51.              express  or  implied,  including,  without limitation,  the
  52.              warranties  of   merchantability  and   the  warranties  of
  53.              fitness for any purpose.
  54.  
  55.  
  56.  
  57.                                    - Page 1 -
  58.                     BNSLIB - An Object Module Library Manager
  59.                                   User's Guide
  60.                     Copyright (C) 1987 by Brand Name Software
  61.                                All Rights Reserved
  62.  
  63.  
  64.  
  65.      Introduction:
  66.  
  67.          Brand Name Software's Object Module Library Manager (BNSLIB) is
  68.          designed expressly for use with Borland  International's  TLINK
  69.          linkage  editor.   BNSLIB  is  command-line  and  response-file
  70.          syntax compatible with  Microsoft's  Library  Manager,  MS LIB.
  71.          Thus,  if you have MS LIB command BATCH files or response files
  72.          set up  to  do routine maintenance,  they should  work  without
  73.          modification (except changing the program name) with BNSLIB.
  74.  
  75.          BNSLIB  can  copy  object  modules  out of libraries created by
  76.          MS LIB, examine MS LIB libraries and convert  MS LIB  libraries
  77.          to  Borland's QLIB format (hereafter referred to as the 'BNSLIB
  78.          format').  In addition, BNSLIB allows you to examine individual
  79.          object module files and provides a  flexible report  format for
  80.          examining both standalone object module files and libraries.
  81.  
  82.           Specifically, the features of BNSLIB are:
  83.  
  84.               o Add object module(s) to a BNSLIB format library.  If the
  85.                 named  library does not exist, you are asked if you want
  86.                 to create a new library:  thus, library creation is just
  87.                 a special case of adding an object module to a library.
  88.  
  89.               o Delete object  module(s)  from a BNSLIB format  library.
  90.                 When the last object module is deleted from the library,
  91.                 an 'empty library' remains (as well as the previous .BAK
  92.                 image of that library).
  93.  
  94.               o Copy object module(s) from a BNSLIB  _or_  MS LIB format
  95.                 library.  The named modules are copied out to individual
  96.                 .OBJ files with the module name as the file's root name.
  97.  
  98.               o Combine one or more BNSLIB _or_  MS LIB format libraries
  99.                 (the result is a BNSLIB format library).
  100.  
  101.               o Convert  libraries created with MS LIB to BNSLIB format.
  102.                 BNSLIB  format  libraries  are about  25%  smaller  than
  103.                 MS LIB format libraries and they are processed  somewhat
  104.                 faster by TLINK.
  105.  
  106.               o Examine whole libraries (BNSLIB  _or_  MS LIB format) or
  107.                 individual object module files (produced  by  any  Intel
  108.                 object  format  translator:  Turbo C, MASM, Microsoft C,
  109.                 etc.).
  110.  
  111.          As  you  can see,  BNSLIB  does everything  for  BNSLIB  format
  112.          libraries MS LIB does for MS LIB  format  libraries,  with  the
  113.          same  command  line  or response  file syntax.   The additional
  114.  
  115.                                    - Page 2 -
  116.                     BNSLIB - An Object Module Library Manager
  117.                                   User's Guide
  118.                     Copyright (C) 1987 by Brand Name Software
  119.                                All Rights Reserved
  120.  
  121.  
  122.          features are accessed by way of command line extensions  (which
  123.          also  work  via response file input).  Thus, if you are already
  124.          familiar with MS LIB operation, you can skip the first part  of
  125.          this  Guide  and proceed directly to Part 2, "BNSLIB Extensions
  126.          to MS LIB."
  127.  
  128.          If you're really anxious to get started using  BNSLIB,  you may
  129.          want to just take a look at the on-line help available.   There
  130.          are several screens of on-line help.   To access  them,  simply
  131.          type BNSLIB at the DOS command prompt.
  132.  
  133.          BNSLIB  requires an  IBM  PC/XT/AT  or close compatible with  a
  134.          minimum of 384K _free_ conventional  memory.   BNSLIB  uses any
  135.          available conventional memory  (up to 640K)  for its workspace.
  136.          The larger the  library  (or object module)  being operated on,
  137.          the more conventional memory BNSLIB requires.  Thus, should the
  138.          program abort  with  a  "memory allocation error" message,  try
  139.          freeing up some conventional memory, if possible.   A hard disk
  140.          is highly  recommended,  but not necessary.   BNSLIB is written
  141.          entirely in  Turbo  C  (no  ASM,  in-line or otherwise) and the
  142.          object modules used to compile BNSLIB.EXE are kept in a library
  143.          created and maintained with BNSLIB.
  144.  
  145.  
  146.  
  147.      1. BNSLIB Commands
  148.  
  149.           1.1 General Command Format
  150.  
  151.               The general format of the command line for BNSLIB is:
  152.  
  153.                 bnslib <ol> [/PAGESIZE:<n>] [cmds][,[<lfile>]][,nl]] [;]
  154.  
  155.               Where:
  156.  
  157.                     ol    =  Original library file name.   If no filname
  158.                              extension  is  given,  BNSLIB  assumes   an
  159.                              extension of ".LIB".  A full directory path
  160.                              may be specified.   This  is  the  file  to
  161.                              which <cmds>, if any, will apply.
  162.  
  163.                     n     =  A number (power of 2, range 16 - 32768). If
  164.                              specified,   the   /PAGESIZE:    (or   /P:)
  165.                              parameter is ignored by BNSLIB.
  166.  
  167.                     cmds  =  The  command   list  (explained  in  detail
  168.                              below).  Optional.  If no command  list  is
  169.                              specified,  BNSLIB does a consistency check
  170.                              of the library and produces  a  report  (as
  171.                              discussed  in  Part  2,  below)  if  one is
  172.  
  173.                                    - Page 3 -
  174.                     BNSLIB - An Object Module Library Manager
  175.                                   User's Guide
  176.                     Copyright (C) 1987 by Brand Name Software
  177.                                All Rights Reserved
  178.  
  179.  
  180.                              requested.  The commands in  the  list  are
  181.                              separated by one or more spaces, tabs or by
  182.                              single commas.
  183.  
  184.                     lfile =  This  is  the  name  of the output  file or
  185.                              device for non-error messages from  BNSLIB.
  186.                              To  see  BNSLIB  messages  on  the console,
  187.                              you'd specify 'con' here (after  the  comma
  188.                              which   is  required   if  a   <lfile>   is
  189.                              specified).
  190.  
  191.                     nl    =  An  optional new  library  filename.    The
  192.                              results of applying <cmds> to the  original
  193.                              library  are  written  to this file (except
  194.                              for the copy operation), if specified.   If
  195.                              not  specified,  the  original  library  is
  196.                              saved as <ol>.BAK before  any  changes  are
  197.                              applied to it.
  198.  
  199.                              Note the required comma when this parameter
  200.                              is specified.   If  you  wish  to specify a
  201.                              new  library  name,   but  do  not  wish to
  202.                              specify a <lfile>, follow the  last command
  203.                              (or  the  original  library  name,  or  the
  204.                              /PAGESIZE:  parameter)   with   two  commas
  205.                              followed by the new library name.
  206.  
  207.               The semi-colon terminates the  command  line  (as  does  a
  208.               CR/LF  pair).   It  does  _not_  result in prompts for any
  209.               remaining  parameters  to  be  displayed  (as it does with
  210.               MS LIB).
  211.  
  212.               The general format for the response file for BNSLIB is:
  213.  
  214.                     record #1:   <ol> [/PAGESIZE:<n>]
  215.                     record #2:   <cmd>[,|<space>|<tab>]... [&]
  216.                     record #n:   <lfile>
  217.                     record #n+1: <nl>
  218.  
  219.               Where <ol>, <cmd>, <lfile>  and  <nl>  mean  the  same  as
  220.               described above.   The elipses (...)  following <cmd> mean
  221.               that more than one command may be specified via a response
  222.               file.   Furthermore,  the command list may be continued on
  223.               more than one consecutive line in the file,  provided  the
  224.               last  character  on  each   line  being  continued  is  an
  225.               ampersand (&). If a semi-colon (;) appears anywhere in the
  226.               file,  input  from  the response file is halted and BNSLIB
  227.               begins executing.   Again, the semi-colon does _not_ cause
  228.               prompts for any remaining parameters to be displayed.
  229.  
  230.  
  231.                                    - Page 4 -
  232.                     BNSLIB - An Object Module Library Manager
  233.                                   User's Guide
  234.                     Copyright (C) 1987 by Brand Name Software
  235.                                All Rights Reserved
  236.  
  237.  
  238.  
  239.           1.2 Adding Object Modules to a Library or Creating a Library
  240.  
  241.               The  command  to  add  an object module to a library is as
  242.               follows:
  243.  
  244.                     +<objmodname>
  245.  
  246.               Where <objmodname> is the file specification of the object
  247.               module  filename  to  be added to the library.  A filename
  248.               extension of .OBJ is assumed, but any extension  specified
  249.               will  be  used.   The  file to be added must reside in the
  250.               current working directory.
  251.  
  252.               The full command line syntax to  add  one  object  module,
  253.               named  MYOBJ.OBJ, to a library named MYLIB.LIB would be as
  254.               follows:
  255.  
  256.                     bnslib mylib +myobj
  257.  
  258.               It  is  also possible to specify a list file (for progress
  259.               messages) and/or a new library file.   If  a  new  library
  260.               file  is  specified,  the original library plus the object
  261.               modules contained in the file(s) specified via the command
  262.               list added will be written to the new library.  Otherwise,
  263.               the  library plus  the  object  modules contained  in  the
  264.               file(s) specified will have the same name as  the original
  265.               library and the original library will have been saved with
  266.               the same root name and the extension of .BAK (in the above
  267.               example, MYLIB.BAK).
  268.  
  269.               If  the  original library file does not exist (i.e., there
  270.               is no MYLIB.LIB), you will be prompted as follows:
  271.  
  272.                     Library file does not exist.  Create?
  273.  
  274.               If you answer 'Y' (or 'y'), a new library  containing  the
  275.               object module  files specified in the command list  (in the
  276.               above  example,   there's  just  one  object  module   file
  277.               specified in the command list) will be created.   The  full
  278.               directory path to  the  library file name may be specified.
  279.               If you respond to this prompt with any character other than
  280.               'y' or 'Y', the BNSLIB  session is cancelled  and  you  are
  281.               returned to the DOS prompt.
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.                                    - Page 5 -
  290.                     BNSLIB - An Object Module Library Manager
  291.                                   User's Guide
  292.                     Copyright (C) 1987 by Brand Name Software
  293.                                All Rights Reserved
  294.  
  295.  
  296.  
  297.           1.3 Deleting Library Modules
  298.  
  299.               The command to delete an object module from a  library  is
  300.               as follows:
  301.  
  302.                     -<objmodname>
  303.  
  304.               Where <objmodname> is the module name as it appears in the
  305.               object module's THEADR  (minus  any  filename  extensions)
  306.               record.  This version of the name can be obtained with one
  307.               of the BNSLIB report options discussed in Part 2, below.
  308.  
  309.               The full command line syntax to delete one object  module,
  310.               named  MYOBJ.OBJ,  from a library named MYLIB.LIB would be
  311.               as follows:
  312.  
  313.                     bnslib mylib -myobj
  314.  
  315.               It is also possible to specify a list file  (for  progress
  316.               messages)  and/or  a  new  library file.  If a new library
  317.               file is specified, the original library  with  the  object
  318.               module(s)  specified in  the command list deleted will  be
  319.               written to the new library.   Otherwise,  the library with
  320.               the specified  object module(s) deleted will have the same
  321.               name as the original library and the original library will
  322.               have been saved with the  same root name and the extension
  323.               of .BAK (in the example above, as MYLIB.BAK).
  324.  
  325.               If the original library file  does  not  exist,  an  error
  326.               message is displayed on stderr (the console).
  327.  
  328.  
  329.  
  330.           1.4 Copying Library Modules
  331.  
  332.               The command to copy an object module from a library is  as
  333.               follows:
  334.  
  335.                     *<objmodname>
  336.  
  337.               Where <objmodname> is the module name as it appears in the
  338.               object module's THEADR  (minus  any  filename  extensions)
  339.               record.  This version of the name can be obtained with one
  340.               of the BNSLIB report options discussed in Part  2,  below.
  341.               The  file  name  given  to  the  module  copied out of the
  342.               library is this module name plus the extension  .OBJ.   As
  343.               with MS LIB, the output .OBJ file is placed in the current
  344.               working directory.   You  may,  however,  specify  a  full
  345.               directory path to the library.
  346.  
  347.                                    - Page 6 -
  348.                     BNSLIB - An Object Module Library Manager
  349.                                   User's Guide
  350.                     Copyright (C) 1987 by Brand Name Software
  351.                                All Rights Reserved
  352.  
  353.  
  354.               The  full  command  line syntax to copy one object module,
  355.               named MYOBJ, from a library  named  MYLIB.LIB  to  a  file
  356.               named  MYOBJ.OBJ in the current working directory would be
  357.               as follows:
  358.  
  359.                     bnslib mylib *myobj
  360.  
  361.               It is also possible to specify a list file  (for  progress
  362.               messages).   Any new  library  file specification will  be
  363.               ignored.   No .BAK file is produced as the result of  this
  364.               operation (the original library is not altered).
  365.  
  366.               If the original library file  does  not  exist,  an  error
  367.               message is displayed on stderr (the console).
  368.  
  369.  
  370.  
  371.           1.5 Replacing Library Modules
  372.  
  373.               The command to replace an object module in a library is as
  374.               follows:
  375.  
  376.                     -+<objmodname>
  377.  
  378.               Where <objmodname> is the module name as it appears in the
  379.               object module's THEADR  (minus  any  filename  extensions)
  380.               record.  This version of the name can be obtained with one
  381.               of the BNSLIB report options discussed in Part 2, below.
  382.  
  383.               The full command line syntax to replace one object module,
  384.               named  MYOBJ,  in  a  library  named MYLIB.LIB would be as
  385.               follows:
  386.  
  387.  
  388.                     bnslib mylib -+myobj
  389.  
  390.               It is also possible to specify a list file  (for  progress
  391.               messages)  and/or  a  new  library file.  If a new library
  392.               file is specified, the original library  with  the  object
  393.               module(s) replaced  will  be  written  to the new library.
  394.               Otherwise, the library with the object module(s)  replaced
  395.               will  have  the  same name as the original library and the
  396.               original library will have been saved with the  same  root
  397.               name   and  the  extension of .BAK  (in the example above,
  398.               as MYLIB.BAK).
  399.  
  400.               If the original library file  does  not  exist,  an  error
  401.               message is displayed on stderr (the console).
  402.  
  403.  
  404.  
  405.                                    - Page 7 -
  406.                     BNSLIB - An Object Module Library Manager
  407.                                   User's Guide
  408.                     Copyright (C) 1987 by Brand Name Software
  409.                                All Rights Reserved
  410.  
  411.  
  412.  
  413.           1.6 Extracting Library Modules
  414.  
  415.               The command to extract an object module  from a library is
  416.               as follows:
  417.  
  418.                     -*<objmodname>
  419.  
  420.               Where <objmodname> is the module name as it appears in the
  421.               object   module's   THEADR   record  (minus  any  filename
  422.               extensions). This version of the name can be obtained with
  423.               one of the  BNSLIB  report  options  discussed in  Part 2,
  424.               below. The file name given to the module copied out of the
  425.               library is this module name plus the extension  .OBJ.   As
  426.               with MS LIB, the output .OBJ file is placed in the current
  427.               working directory.  You may specify a  full directory path
  428.               to the library, however.
  429.  
  430.               The full command line syntax to extract one object module,
  431.               named MYOBJ, in a library  named  MYLIB.LIB  would  be  as
  432.               follows:
  433.  
  434.                     bnslib mylib -*myobj
  435.  
  436.               It  is  also possible to specify a list file (for progress
  437.               messages) and/or a new library file.   If  a  new  library
  438.               file is specified,  the original library minus  the object
  439.               module(s)  extracted will be written to the  new  library.
  440.               Otherwise,   the   library  minus   the  object  module(s)
  441.               extracted will have the same name as the original  library
  442.               and the original library will  have  been saved  with  the
  443.               same root  name and  the extension of  .BAK  (in the above
  444.               example, MYLIB.BAK).
  445.  
  446.               If the original library file  does  not  exist,  an  error
  447.               message is displayed on stderr (the console).
  448.  
  449.  
  450.  
  451.           1.7 Combining Libraries
  452.  
  453.               The command to add an object module to a library may  also
  454.               be used  to  combine  one  (BNSLIB  format)  library  with
  455.               another.  This command looks like the following:
  456.  
  457.                     +<libname>.LIB
  458.  
  459.               Where <libname> is the file name of the library file to be
  460.               combined with the original library. The filename extension
  461.  
  462.  
  463.                                    - Page 8 -
  464.                     BNSLIB - An Object Module Library Manager
  465.                                   User's Guide
  466.                     Copyright (C) 1987 by Brand Name Software
  467.                                All Rights Reserved
  468.  
  469.  
  470.               .LIB _must_ be specified (otherwise, BNSLIB will look  for
  471.               a  file in  the  current  directory  with  the  root  name
  472.               <libname> and an .OBJ extension.   The source library file
  473.               for  the combine operation  must  reside  in  the  current
  474.               working directory.
  475.  
  476.               The full command line syntax  to combine a  library  file,
  477.               named LIBNAME.LIB, to a library named MYLIB.LIB  would  be
  478.               as follows:
  479.  
  480.                     bnslib mylib +libname.lib
  481.  
  482.               It  is  also possible to specify a list file (for progress
  483.               messages) and/or a new library file.   If  a  new  library
  484.               file is specified,  the original  library plus all  of the
  485.               object modules in  the specified  source  library will  be
  486.               written  to  the  new  library.   Otherwise,  the original
  487.               library plus all of the object modules  in  the  specified
  488.               source  library  will  have  the same name as the original
  489.               library and the original library will have been saved with
  490.               the same root name and the extension of .BAK (in the above
  491.               example, MYLIB.BAK).
  492.  
  493.               If  the  original  library  file  does  not exist an error
  494.               message will be displayed on stderr (the console).
  495.  
  496.  
  497.  
  498.           1.8 Checking Library Consistency
  499.  
  500.               The command to check the consistency  (i.e., integrity) of
  501.               a library (or object module, see  below) is  _no command_.
  502.               That's  right,  just  don't specify any command and BNSLIB
  503.               will run through the  library  and  check  it's  validity.
  504.               Unless otherwise specified (see below), or unless an error
  505.               is discovered, nothing will be sent  to  the  <lfile>.  In
  506.               other words, no news is good news.
  507.  
  508.               You may specify a full  directory  path  to  the  original
  509.               library  file.   If  the  original  library  file does not
  510.               exist, an error message will be displayed on  stderr  (the
  511.               console).
  512.  
  513.               You  may  use  this  command with  libraries in the BNSLIB
  514.               format _or_ the MS LIB format.
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.                                    - Page 9 -
  522.                     BNSLIB - An Object Module Library Manager
  523.                                   User's Guide
  524.                     Copyright (C) 1987 by Brand Name Software
  525.                                All Rights Reserved
  526.  
  527.  
  528.  
  529.           1.9  General Considerations
  530.  
  531.               More than one command or command type may be specified per
  532.               BNSLIB  session.  Indeed, you may specify as many commands
  533.               as will fit on the command line or as many as you want  to
  534.               stuff in a response file (up to 100 total -- including the
  535.               original library name,  the  <lfile>  and the new  library
  536.               name).   Regardless  of  the  order in which  commands are
  537.               entered on the command line or in a  response  file,  they
  538.               are always executed in the following order:
  539.  
  540.                     1. Copy commands (*)
  541.                     2. Delete commands (-)
  542.                     3. Add commands (+)
  543.  
  544.               The Replace command is treated as a  Delete command and an
  545.               Add command.   Similarly,  the Extract commmand is treated
  546.               as a  Copy command followed by a Delete command.   This is
  547.               the case regardless of  how  the  composite  commands  are
  548.               actually issued  (i.e.,  regardless of whether you specify
  549.               -+ or +- for Replace or -* or *- for Extract).
  550.  
  551.               Within each of the  three basic  command  categories,  the
  552.               module names are arranged in  ascending  alphabetic  order
  553.               before any command operations are performed.  Modules in a
  554.               BNSLIB  format  library are always  stored  physically  in
  555.               ascending alphabetic order by module name.
  556.  
  557.               In addition to the explicit conversion operation mentioned
  558.               in Part 2 of  this  Guide  for  converting  MS LIB  format
  559.               libraries to BNSLIB format libraries,  implicit conversion
  560.               is  performed  if  any  of  the  following  operations are
  561.               carried out on an MS LIB format library:
  562.  
  563.                    1.  Add module or add library
  564.                    2.  Delete/Replace module
  565.  
  566.               If  no  new  library  file  is  specified,  the  .BAK file
  567.               resulting from the _first_ application  of  one  of  these
  568.               operations to the MS LIB library will be in MS LIB format.
  569.               The new .LIB file will be in  BNSLIB  format.   If  a  new
  570.               library  name  is  specified, the .BAK file is not created
  571.               and the original library remains in  MS LIB  format  while
  572.               the new library is written in BNSLIB format.
  573.  
  574.               It  is important in the former case (where the MS LIB file
  575.               winds up in the .BAK file) to rename the old  MS LIB  file
  576.               to  something  other  than  .BAK if you want to retain it.
  577.               Otherwise, the next operation that changes the new, BNSLIB
  578.  
  579.                                    - Page 10 -
  580.                     BNSLIB - An Object Module Library Manager
  581.                                   User's Guide
  582.                     Copyright (C) 1987 by Brand Name Software
  583.                                All Rights Reserved
  584.  
  585.  
  586.               format,  version  of  the  library  will  overlay the .BAK
  587.               version of the file and your MS LIB format version of  the
  588.               library will be gone for good.
  589.  
  590.               Note  that  if  you just copy (*) a module out of a MS LIB
  591.               format library, no implicit conversion is performed.   The
  592.               .LIB file will still be in the MS LIB format when the copy
  593.               operation is complete.  Thus,  you may copy object modules
  594.               from your  favorite  MS LIB  format libraries using BNSLIB
  595.               without fear of altering the MS LIB libraries.
  596.  
  597.  
  598.  
  599.      2. BNSLIB Extensions to MS LIB
  600.  
  601.           2.1 Flexible Reporting Options
  602.  
  603.               BNSLIB  allows  you  to examine some of the 'internals' of
  604.               object modules, whether they are stored in  a  library  or
  605.               are  standalone  .OBJ  files.   BNSLIB  can examine either
  606.               MS LIB format libraries or BNSLIB format libraries.    Any
  607.               standalone  Intel  object format file can be examined, not
  608.               just those produced  by  Turbo  C.   In  addition,  BNSLIB
  609.               allows  you  to  determine the 'level' of information that
  610.               will be reported from the examination.
  611.  
  612.               The syntax for specifying the level of information  detail
  613.               for a particular report is as follows:
  614.  
  615.                  bnslib <library>[(<displaylist>)][, <listfile>]
  616.  
  617.               Notice that <listfile> is shown as optional.  Technically,
  618.               it is.  But, it would be pretty silly to order a report on
  619.               a library or object module and then  not  send  the report
  620.               anywhere you could look at it, right? So, in reality, this
  621.               parameter is required.   Also,  note that <displaylist> is
  622.               enclosed in parentheses.  When a report is desired,  these
  623.               are required and there may be no space between the end  of
  624.               <library> and the left (starting) parenthesis.
  625.  
  626.               The lowest level of reporting is to provide no information
  627.               unless there is an  internal  problem  with  the  library.
  628.               This   is   equivalent  to  MS LIB's  'consistency  check'
  629.               operation.  Example:
  630.  
  631.                     bnslib mylib
  632.  
  633.               would display nothing (save the advisory message mentioned
  634.               in Part 1 of this Guide) if all went well.   If  there was
  635.               something  wrong with MYLIB, error message(s) would appear
  636.  
  637.                                   - Page 11 -
  638.                     BNSLIB - An Object Module Library Manager
  639.                                   User's Guide
  640.                     Copyright (C) 1987 by Brand Name Software
  641.                                All Rights Reserved
  642.  
  643.  
  644.               on stderr (the console screen).
  645.  
  646.               The <displaylist> is composed of one  or  more  characters
  647.               from the following list (the characters may  be  typed  in
  648.               upper or lower-case, only lower-case is shown here):
  649.  
  650.                     h:  Displays the object module's name  (each module,
  651.                         if a library is being examined) and the module's
  652.                         combined code and data size (and, if  a  library
  653.                         is   being  examined,  the  particular  module's
  654.                         offset  from  the  beginning  of  the  library).
  655.                         Example:
  656.  
  657.                             bnslib mylib(h), con
  658.  
  659.                         Note  that ', con' specifies the console device,
  660.                         but this could just as well have been ', prn' or
  661.                         ', drive:\path\filename'.
  662.  
  663.  
  664.                     c:  Displays  the  comment  records  in  the  object
  665.                         module  (each module,  if  a  library  is  being
  666.                         examined).   This level includes  the  'h' level
  667.                         (thus, when c is specified, BNSLIB reports as if
  668.                         h had also been specified).  Example:
  669.  
  670.                             bnslib mylib(c), con
  671.  
  672.                         This would display the module's name,  its  code
  673.                         and  data size (and offset, if in a library) and
  674.                         the  human-readable  content  of  each   comment
  675.                         record  in  the  module.   Comment  records  are
  676.                         placed  in  the  .OBJ  file  by   the   language
  677.                         translator  and  are  used for various purposes,
  678.                         including passing  information  to  the  linkage
  679.                         editor.  They can be interesting!
  680.  
  681.  
  682.                     s:  Displays the public symbols in the object module
  683.                         (each  object  module,  if  a  library  is being
  684.                         examined).  This  level,  like  the  'c'  level,
  685.                         includes the 'h' level.  Example:
  686.  
  687.                              bnslib mylib(s), con
  688.  
  689.                         The   symbols   are   displayed   in   ascending
  690.                         alphabetic  order  within  each  module  in  the
  691.                         library (or within the object module file) being
  692.                         examined.    A space appears between each symbol
  693.                         and symbol names are not broken across lines.
  694.  
  695.                                   - Page 12 -
  696.                     BNSLIB - An Object Module Library Manager
  697.                                   User's Guide
  698.                     Copyright (C) 1987 by Brand Name Software
  699.                                All Rights Reserved
  700.  
  701.  
  702.                     n:  Displays  the segment  and  group  names in  the
  703.                         object  module  (each  module,  if  a library is
  704.                         being examined).  This level includes  both  the
  705.                         's' level and the 'h' level.  Example:
  706.  
  707.                              bnslib mylib(n), con
  708.  
  709.  
  710.                     w:  Wait between modules.   This option applies only
  711.                         to  display  lists  given  in  conjunction  with
  712.                         library  names.   If  given  with an object file
  713.                         name, it is simply ignored.  Also,  if  this  is
  714.                         the only option given,  it is ignored.  Finally,
  715.                         if the  <listfile>  is anything except CON, this
  716.                         option,  if specified,  is ignored.
  717.  
  718.                         When  active,   this  option  causes  the report
  719.                         output  to pause  between  each  module  in  the
  720.                         library.  The prompt:
  721.  
  722.                              more ->
  723.  
  724.                         is displayed on the console.    Pressing any key
  725.                         (except CTRL-C  or  CTRL-BREAK) will advance the
  726.                         display  to  the  next   object  module  in  the
  727.                         library. If CTRL-C or CTRL-BREAK is pressed, the
  728.                         program terminates gracefully back to DOS.
  729.  
  730.               Obviously,  the  lowest level of reporting (aside from the
  731.               'no report, consistency check' level) is to  specify  only
  732.               'h.'  But,  more  complex  reports  can  be  generated  by
  733.               specifing a report option  list.   The  highest  level  of
  734.               reporting possible with BNSLIB is:
  735.  
  736.                     bnslib mylib(cn), con
  737.  
  738.               This would display the comment records, the public symbols
  739.               (because 'n' includes 's'), the segment and  group  names,
  740.               and the module name and size information (because both 'c'
  741.               and 'n' include 'h') for each module in MYLIB.LIB.
  742.  
  743.  
  744.  
  745.           2.2 Examining Individual Object Modules
  746.  
  747.               BNSLIB allows you to examine standalone object files.  The
  748.               syntax is _exactly_ the same as that given in section 2.1,
  749.               above.  However, to indicate that an object  file  is  the
  750.               subject  of  the  examination and report, you must preface
  751.               the file's name with the '#' character.  Thus,
  752.  
  753.  
  754.                                   - Page 13 -
  755.                     BNSLIB - An Object Module Library Manager
  756.                                   User's Guide
  757.                     Copyright (C) 1987 by Brand Name Software
  758.                                All Rights Reserved
  759.  
  760.  
  761.                     bnslib #myobject(cn), con
  762.  
  763.               would give a 'full report' on the  .OBJ  file  'myobject.'
  764.               Note  that  BNSLIB assumes the file's extension is '.obj'.
  765.               Thus, it is not necessary to provide this information with
  766.               the  command. But, if an extension is specified it will be
  767.               used.
  768.  
  769.  
  770.  
  771.           2.3 Converting MS LIB Format Library to BNSLIB Format
  772.  
  773.               You can convert your existing MS LIB format  libraries  to
  774.               BNSLIB format.  This has several advantages:
  775.  
  776.                    1.   If  you  don't  have  MS LIB,  you  can  now  do
  777.                         complete  library  maintenance  on  those MS LIB
  778.                         libraries that came with your  favorite  utility
  779.                         package (or with Turbo C).
  780.  
  781.                    2.   BNSLIB format libraries are approximately 20-25%
  782.                         smaller  than  MS LIB  format  libraries.   This
  783.                         saves disk space.
  784.  
  785.                    3.   TLINK  will  process  BNSLIB   format  libraries
  786.                        faster than MS LIB format libraries. This speeds
  787.                        the link phase of Turbo C program development.
  788.  
  789.               The command to convert from a  MS LIB  format library to a
  790.               BNSLIB format library is:
  791.  
  792.                     bnslib !<mslibrary> <bnslibrary>[, <listfile>]
  793.  
  794.               The <listfile> should be specified if you want to view (or
  795.               save) 'progress' messages from BNSLIB.  Report options, if
  796.               specified, are ignored.
  797.  
  798.               The  <mslibrary>  is  not altered.  Full path names may be
  799.               specified for either library.  If <bnslibrary> exists, you
  800.               will  be  asked if you're _sure_ you want to overwrite it.
  801.               The exclamation point is required.  It  must  preceed  the
  802.               <mslibrary> parameter with no intervening spaces.
  803.  
  804.  
  805.  
  806.  
  807.  
  808.  
  809.                         -- END OF BNSLIB USER'S GUIDE --
  810.  
  811.                                    - Page 14 -
  812.